Web Service Extension

An AgilePart activity that accesses a Web Service and its methods which are registered in AgilePoint Envision. The user can select the appropriate Web Service and its specific method using the Web Service shape. The Web Service Extension uses SOAP calls over HTTP and allows for schema mapping between the AgilePoint application schema and the Web method's request schema.

Design-Time Properties

NOTE: The following properties are always available for all instances of the AgilePart AgileShape. However, additional design-time properties will often be available for specific instances of the AgilePart AgileShape. The names, purposes, effect, and availability of these additional design-time properties will depend upon the specific .NET class associated with the AgilePart AgileShape instance.

(Name)

ReadOnly

Default value: Web Service

The display name of the AgileShape.

(UID)

ReadOnly

Default value: Web Service

The ID that uniquely identifies this AgileShape from all others within the same process template.

Description

Optional

NOTE: This property is ignored at runtime.

A description of the AgileShape. This property is primarily used as a means of recording additional notes, comments, and details about this AgileShape in order to make the process template more understandable to process modelers.

Incoming Email

Optional

The name of an Email Template that should be used to generate an automatic email notification when this AgileShape is entered at runtime. If this property is left blank, then an email notification will not be sent automatically when the AgileShape is entered at runtime. If this property is not blank, then an email notification will be dynamically constructed and sent at runtime (when the AgileShape is entered) using the specified Email Template.

Outgoing Email

Optional

The name of an Email Template that should be used to generate an automatic email notification when this AgileShape is exited at runtime. If this property is left blank, then an email notification will not be sent automatically when the AgileShape is exited at runtime. If this property is not blank, then an email notification will be dynamically constructed and sent at runtime (when the AgileShape is exited) using the specified Email Template.

Audit Level

Default value: High

This property determines the amount of process related data that is recorded to the workflow database. This property can be set at either the Process Template Properties layer or at the individual AgileShape layer. This property allows you to control the level of granularity in terms of the amount of process related data that is recorded to the workflow database. This property can be set to the following specific values:

• High
  
  This value indicates that AgilePoint will record all data about the activity or process to the database.

• Low
  
  This value indicates that AgilePoint will only allow a certain amount of data to be recorded to the database. This option provides a level of control over the granularity of AgilePoint process-related data that is stored in the AgilePoint workflow database, giving some flexibility in the audit trail records by filtering out unnecessary data.

SessionMode

Default value: Single 

 This property can be set to the following specific values:

• Single
  
  If it is set to single, then ONLY one session is effective, meaning that in a loop scenario as shown below, the engine would cancel a task from the previous session automatically.

• Multiple
  
  If it is set to multiple, then multiple sessions can be effective in a loop scenario, and the process will wait for all tasks to complete and not cancel any previous tasks.

 

Wait All Incoming

NOTE: This property is ignored at runtime unless the AgileShape has multiple In-Connectors.

Default value: False

When an AgileShape has multiple direct predecessors (i.e. it has multiple In-Connectors leading directly from other AgileShapes), this property determines how many of the predecessor AgileShapes must be exited (at runtime) before this AgileShape can be entered (at runtime). This property can be set to the following specific values:

• False
  This value indicates that the AgileShape will be entered (at runtime) as soon as any one of the AgileShape’s direct predecessors are exited (at runtime).
  
  NOTE: This value is functionally equivalent to using the Or AgileShape (with Exclusive property set to False) between this AgileShape and its direct predecessors.

• True (Dynamic)
  This value indicates that the AgileShape will be entered (at runtime) only after all of the AgileShape’s “enterable” direct predecessors are exited (at runtime). If any of the direct predecessors are un-enterable (e.g. they will never be entered in this process instance because conditional logic in the process bypassed them) and therefore un-exitable, then those predecessors are not required to be exited before this AgileShape is entered.
  
  NOTE: This value is functionally equivalent to using the And AgileShape (with the Dynamic property set to True) between this AgileShape and its direct predecessors.
• True (Static) This value indicates that the AgileShape will be entered (at runtime) only after all of the AgileShape’s direct predecessors are exited (at runtime).
  
  NOTE: This value is functionally equivalent to using the And AgileShape (with the Dynamic property set to False) between this AgileShape and its direct predecessors.
  
  NOTE: If any of the direct predecessors are un-enterable (see above), then this AgileShape will never be entered, and the process instance may be permanently delayed at this AgileShape.

 

AssemblyName 

Read Only

The name of the .NET assembly containing the specific AgilePart component that this AgileShape instance is associated with.

ClassName

Read Only

The fully qualified Type name (including the namespace) of the .NET class (in the .NET assembly specified by the AssemblyName property) that represents the specific AgilePart component that this AgileShape instance is associated with.

Method

Read Only

The name of the method (in the .NET class specified by the ClassName property) that will be invoked at runtime (when the AgileShape is entered).

ConfigureAttachments  

Allows you to attach documents to the activity that are accessed from the process repository. For more information, see Process Repository.

Reference URL

Allows you to associate an URL to the shape that is used in the process repository. For more information, see Process Repository.

ExceptionHandlerScope   

Default value: Local

Specifies the value which determines how AgilePoint Server will handle an AgilePart exception. Two options are available: Local or Global.

• Local
  
  This value indicates the exception handling (i.e., error message and status) information for an AgilePart within a single process instance will be saved to the custom attribute defined in the SaveErrorMessageTo and SaveStatusTo properties.
  
  
  
  
• Global
  
  This value indicates the exception handling (i.e., error message and status) information is handled the same as the Local option, but includes the extended ability to call on a custom AgileConnector to handle the exception as desired.

SaveErrorMessageTo

Default value: ErrorMessage

Specifies the name of a custom process attribute that should be updated if the AgileShape causes an error at runtime. If such an error occurs, a message containing information about the error will be stored in the custom process attribute specified by this property.

SaveStatusTo

Default value: Success

Specifies the name of a custom process attribute that should be updated when the AgileShape is exited. When the AgileShape is exited at runtime, the value of the AgileShape’s Status property will be stored (as a String) in the custom process attribute specified by this property.

MethodName

NOTE: This property can only be updated via the Configure property. See that property for additional information.

The name of the Web method (in the Web service specified by the URL property) that will be invoked at runtime (when the AgileShape is entered).

URL

NOTE: This property can only be updated via the Configure property.

See that property for additional information. The URL of the Web service that this AgileShape instance is associated with.

Configure

This property allows the process modeler to configure which Web service method should be invoked at runtime. It also allows the process modeler to map the 'response' to the AgilePoint application schema node(s) or to a custom attribute that will be used to store the Web service method’s return value (if any).

1. The "Webservice" control box contains the controls to get the WSDL of the Web service either by entering the Web service URL or by browsing for a WSDL file on the file system.
   
   For selecting the Web service URL, you can directly enter the URL of the Web service in the text box if you know the exact URL, or you can invoke the UDDI explorer by clicking on the UDDI button beside the text box and select the URL from the UDDI explorer. After getting the URL of the Web service, you can click the green arrow connect button to connect to the Web service and get all the methods. If you do not have sufficient access privileges to the Web service, a window will appear to enter the alternative credentials that can be used to connect to the Web service. 
   
   
2. Select the method you want to execute for this activity.
   
   
3. Enter the Endpoint URL (the URL of the Web service).
   
   NOTE: If the actual Endpoint URL can change at runtime, you can enter the name of a Custom Attribute that will hold the actual Endpoint URL value to be used at runtime.
   
4. To configure the custom process attributes for the parameters and/or return value, simply click on an attribute (e.g. $piID) to highlight it, and then click on it again to modify the value.
   
   
5. The "Request" tab allows you to configure the mapping for input from the application schema to the Web Method’s request schema. On the left side of the window shows the application schema, on the right is the Web service schema.
   
   Map the fields from the application’s schema to the Web service schema fields by dragging and dropping from the schema to the database pane. You will see the connection lines appear as shown above. The connection lines may show different colors based on the compatibility of the data types as follows:
   

• Green: The data type matches.

• Blue: The data type does not match, the system will handle the conversion.

• Red: The data type does not match, custom data conversion is required. In this case, click the Add button and add the custom mapping code as necessary to handle the data conversion.
  

 

6. You can also specify the values that need to be passed to the Custom Headers if the Web method contains any. The Custom Headers window will list all the properties in the Custom Headers on the left hand side. You can enter the corresponding values that need to be passed for these properties in the text boxes on the right hand side. If the values for these properties are only available at runtime, you can enter the name of the custom attributes that will hold these values prefixed with a %.
   
   
7. The "Response" tab allows you to configure how the response from the Web service should be handled. You can choose either to map the response to the AgilePoint application schema by using the Schema Mapper window to configure the 'response' schema mapping to theAgilePoint application schema, or you can choose to store the 'response' in a custom attribute by entering the name of the custom attribute for which the response value will be stored at runtime.
   
8. The "Security" tab configures the SSL properties of the Web service AgilePart. You can select the “Log SSL Authentication Failures” option to log any problems encountered during the SSL Authentication. If it is selected, the system logs any problems encountered while doing SSL authentication before aborting the insecure connection to the server. Also if the Web service that is being called requires the Client to provide a Certificate to authenticate itself, you can click the “…” button beside the Client Certificates to open the Client Certificates window that allows you to select the certificates to be sent.
   
   The Client Certificates window consists of a table that shows a summary view of all the certificates that have been selected.
   
   The “Add from file..” button allows you to add a certification from a certification (.cer) file. This will present a file selection window that allows you to pick a .cer file.
   
   The “Add from store..” button allows you to pick the certificates from the X509 Certificate Store.
   
   The “Remove” button removes the selected certificate from the list of certificates that are sent with the HttpWebRequest.
   
   The “View” button will show the details of the selected certificate.

Credential

Default value: {None}

This property allows the process modeler to configure which authentication credentials (i.e. windows user account) should be used to invoke the Web service method at runtime. Click the Ellipses button to open the Login dialog (as shown below).

Proxy

This property allows you to specify that a proxy server should be used to connect to the Web service at runtime. It allows you to bypass the permission constraints on the local machine.

Timeout

Default value: 600

Specifies the maximum amount of time (in seconds) that should be allowed for the completion of the Web service call associated with this AgileShape.